[DOCS#EV-6623]: Fill HEP policy recommendation docs gaps — selector syntax and status lifecycle#2734
Open
electricjesus wants to merge 2 commits into
Open
Conversation
…lifecycle Backfill two release-blocking gaps surfaced in EV-6623 against the HEP policy recommendation docs merged in tigera#2658. hostEndpointSpec.selector had no Calico selector operator reference. Add a "Scope recommendations to specific hosts" section on the HEP page with a worked example and a common-pattern table, plus a "Selectors" section on the PolicyRecommendationScope reference page rendering the existing <Selectors /> partial that was imported but unused. The policyrecommendation.tigera.io/status annotation lifecycle (Learning -> Stabilizing -> Stable) was undocumented. Add a "Track recommendation readiness" section on the HEP page with kubectl one-liners and a tip to wait for Stable before enforcing, and a paired "Annotations on generated recommendations" / "Recommendation status lifecycle" pair on the reference page that documents the full annotation family and the transitions driven by lastUpdated, interval, and stabilizationPeriod. Refs EV-6623.
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR backfills missing Calico Enterprise “next” documentation for the host policy recommendation feature by adding (1) selector/operator syntax guidance for hostEndpointSpec.selector and (2) the engine-driven recommendation readiness lifecycle (Learning → Stabilizing → Stable) tied to policyrecommendation.tigera.io/status.
Changes:
- Adds a new “Selectors” section to the PolicyRecommendationScope reference and links HostEndpoint selector docs to it.
- Documents the
policyrecommendation.tigera.io/*annotation family and status lifecycle transitions on generated recommendations. - Updates the host policy recommendations how-to with host scoping examples and kubectl commands to read readiness status.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| calico-enterprise/reference/resources/policyrecommendations.mdx | Adds selectors reference rendering plus new annotation/status lifecycle documentation; links HostEndpoint selector field to the selectors section. |
| calico-enterprise/network-policy/recommendations/hep-policy-recommendations.mdx | Adds “scope by selector” guidance and a “track readiness” section with status meanings and kubectl JSONPath examples. |
Comments suppressed due to low confidence (1)
calico-enterprise/reference/resources/policyrecommendations.mdx:108
- The new “Selectors” section states it applies to both
namespaceSpecandhostEndpointSpec, but only the HostEndpointSpec table’sselectorrow links readers to#selectors. To avoid leaving the namespace selector without operator syntax guidance, either add the same#selectorsreference to the NamespaceSpecselectorrow or adjust this section text to only claim coverage for the fields that link here.
## Selectors
The `selector` fields on `namespaceSpec` and `hostEndpointSpec` accept
the same label-selector expression language used elsewhere in Calico
network policy.
ctauchen
reviewed
May 20, 2026
Collaborator
ctauchen
left a comment
ctauchen
left a comment
There was a problem hiding this comment.
Some suggestions for you, thanks for this!
HEP page (hep-policy-recommendations.mdx): - Use plain "host endpoint" in generic prose; reserve `HostEndpoint` for the resource name (Chris). - Reword "matches the HostEndpoint labels you want to cover" to "matches the labels of the host endpoints you want to cover" (Chris). - Replace the inline kubectl patch that needed shell single-quote escapes (`'\''`) with a `--patch-file=/dev/stdin` heredoc carrying a YAML patch. Removes the escape question entirely (Chris). - Introduce the selector-pattern table with a descriptive sentence (Chris). - Rewrite the pattern-table "Goal" cells as imperatives that match the column header (Chris). - Replace "settled down enough to enforce" with "stopped changing long enough to be ready to enforce" (Chris). - Add an introductory sentence before the status-annotation table (Chris). - Tighten the Stabilizing row boundary from "but less than stabilizationPeriod" to "but no more than stabilizationPeriod" so it matches the source check `diff <= rec.stabilization` and the wording on the reference page (Copilot). - Replace "mid-Stabilizing will be knocked back" with "during a Stabilizing period returns to" (Chris). - Lowercase `Learning`/`Stabilizing` in the tip's prose so they read as states, not literals (Chris). Reference page (policyrecommendations.mdx): - Clarify that `lastUpdated` tracks the generated staged policy's spec, not the PolicyRecommendationScope spec (Copilot). - Apply the same clarification to the lifecycle intro that referenced "the spec" (Copilot). - Link the NamespaceSpec `selector` row to the new `#selectors` anchor so both selectors are reachable from the section that claims to document both (Copilot). Refs EV-6623.
Collaborator
|
LGTM for me. Need other approvals or ready to merge? @electricjesus |
Member
Author
|
Thanks @ctauchen! I will wait for @xiumozhan to confirm first |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Product Version(s):
Calico Enterprise (next / unreleased — applies to the docs merged in #2658).
Issue:
Link to docs preview:
Once Netlify builds, the two updated pages are:
/calico-enterprise/next/network-policy/recommendations/hep-policy-recommendations/calico-enterprise/next/reference/resources/policyrecommendationsSummary
Backfills two release-blocking gaps surfaced during the CNX-R1355 / CNX-T5996 manual test cycle audit of #2658.
1.
hostEndpointSpec.selectorhad no operator syntax referenceNeither the HEP page nor the PolicyRecommendationScope reference page documented the Calico label-selector syntax (
==,in {…},has(),all(), boolean composition, …) that the field accepts. A user landing onhostEndpointSpec.selectorfor the first time had no path to the operator reference.Changes:
### Scope recommendations to specific hostssection with a worked example (environment == 'prod') and a common-pattern table, linking to the new selectors anchor on the reference page.## Selectorssection that renders the<Selectors />partial — the import was already at the top of the file but never rendered.selectorrow in the HostEndpointSpec table now points at#selectors.2.
policyrecommendation.tigera.io/statuslifecycle was undocumentedThe HEP page describes the user-controlled
stagedActionlifecycle (Learn/Set/Ignore), and mentionsstabilizationPeriodonly as a config knob. The engine's own readiness signal — thepolicyrecommendation.tigera.io/statusannotation moving throughLearning → Stabilizing → Stable— wasn't documented anywhere. Users had no way to answerwhen is my recommendation ready to enforce?.Verified against source:
policy-recommendation/pkg/calico-resources/stagednetworkpolicy.go:53-57andpkg/engine/recommendation.go:493-534.Changes:
### Track recommendation readinesssection with the status table, the exact transition conditions (> 2 × interval,> stabilizationPeriod), the reset-on-modify behavior, twokubectlone-liners (single + bulk) for reading the annotation, and a tip to wait forStablebefore accepting/enforcing.## Annotations on generated recommendationssection documenting the fullpolicyrecommendation.tigera.io/*annotation family (status,lastUpdated,scope,name,namespace), plus a### Recommendation status lifecyclesubsection that the HEP page cross-links to.Not in scope
The reference page imports several other partials (
Servicematch,Serviceaccountmatch,Ports,Entityrule,Icmp,Rule) that are never rendered — the page truncates at the HostEndpointSpec table. Looks like a separate gap from the original fork ofglobalnetworkpolicy.mdx. Leaving for a follow-up so this PR stays focused on EV-6623.SME review
Merge checklist
BUILD_NEXT=true yarn buildproduced no new broken-link errors against the two changed pages)